Application is a PDF or MS Word document that includes:
12/29/21
12/21/21
I extensively revised the abstract and wrote a new title to bring more people into the workshop. I also made it clear that participants do not need any technical skills.
GitHub and R Studio are rock solid tools, but using online services and downloaded software is always a worry. In case they misbehave, I do have backup plans:
The ABLE 2022 GitHub repository is live. I’ve already uploaded the Markdown document with the handouts for this workshop, plus the conversions to HTML and Word.docx. There will be a folder there with the finalized Writing Resource Guide .md files in a Markdown document, then converted it to MS Word for final formatting and submission. The original “.md” file is available to participants from this workshop’s
A. Daniel Johnson, Wake Forest University, Department of Biology, 1834 Wake Forest Road, Winston-Salem NC 27109, USA. johnsoad@wfu.edu
At the 2021 ViABLE conference we presented our “six elements model” for teaching scientific writing in multi-section introductory biology courses. One of our essential tools is a standardized Scientific Writing Resource Guide that students and instructors use across multiple courses. In response to many requests that we share our Resource Guide, it now is available as an open-source book that others can modify to meet their individual needs.
To make our Guide easy to maintain and convert to different formats, we wrote it using Markdown. This lightweight markup is ideal for writing lab materials because authors write a text once, then output it in multiple formats like HTML5 for web pages, or Word documents for printed handouts. Groups of Markdown files can be combined into interactive online books.
Markdown takes ~20 minutes to learn, and marked text remains readable. To demonstrate it, workshop handouts were written in Markdown. The original “.md” file is under “Sample Files” in the workshop’s GitHub repository.
Participants in this workshop do not need any prior technical knowledge beyond basic computer skills. They will learn to use Markdown by editing existing pages from our Guide, creating new pages, and converting both into formatted Word and HTML5 documents. We will demonstrate how to use R Studio to assemble collections of Markdown documents into books, and how to use GitHub to manage and share writing project files.
Participants will leave with a full copy of our Scientific Writing Resource Guide that they can revise to match their course requirements, the tools for writing and converting Markdown files to their preferred format, and a GitHub account where they can back up their project. Those interested can learn how to launch new book projects of their own, or contribute to our published edition of the Resource Guide.
Keywords: scientific writing, writing guidelines, Markdown, lab development tools, R Studio, web publishing
Scientific writing helps students learn to state problems and present claims precisely, summarize evidence to support those claims, and explain their reasoning. For many years, our Scientific Writing Resource Guide has been one of our essential tools for teaching scientific writing in multiple courses. The Guide focuses on writing a lab report that models a journal article because the same components are used in most other forms of scientific communication too. Our general format conforms to the Council of Science Editors (8e) standards, with some modifications to make writing easier for students just starting out. The Resource Guide includes sections on data visualization, basic biostatistics, and how to cite literature.
In 2021 we updated, expanded, and published our Writing Resource Guide. Our goal is to support two audiences: undergraduates learning the craft of scientific writing, and biology instructors who either teach scientific writing to undergraduates or supervise teaching assistants who do. Rather than try to write one guide meet the needs of every possible audience, we designed ours to be an evolving collaborative resource that we have released under terms of a Creative Commons BY-NC-SA 4.0 license .
The Guide is written in plain text using Markdown, so users can convert the Guide to whatever format is needed. Participants in this workshop will learn how to access and modify the Resource Guide using free tools. They can edit, extend or modify our Guide as needed to fit their particular needs and requirements, so long as they attribute its original source and do not use it commercially.
Producing the shared Resource Guide introduced us to Markdown, a lightweight markup language that is extremely easy to use. Markdown is a great solution to the challenge of writing lab documents that may have to go to multiple destinations. With Markdown, authors write a text once then convert it into multiple file formats. It takes less than 20 minutes to learn most of the Markdown syntax needed for routine writing tasks, and marked-up text is still easy to read. Markdown can be converted to HTML5 so it plays well with most LMSs. It also can be converted directly into MS Word or PDF documents. With additional free tools, collections of Markdown documents can be compiled into rich, interactive online books.
To demonstrate the versatility of Markdown, all of the handouts for this workshop were written in Markdown. The original “.md” file and various converted versions are available in the “Sample Files”” folder in the workshop’s ABLE 2022 GitHub repository.
The main goals of the workshop are:
Participants in this workshop do not need any technical skills beyond basic computer skills. The exercises assume no prior knowledge of Markdown, the other tools, or computer coding.
Before the workshop participants should try to install the software tools. These tools are not essential, but make working with .md files easier. We will troubleshoot any installation problems at the start of the workshop.
In the first half of the workshop participants will make personal copies of the files for our Resource Guide. Then they will try creating and editing Markdown documents using two tools: R Studio and a plain text editor. Finally they will save their new files to their personal GitHub account.
In the second half of the workshop, participants will learn how to use either R Studio or standalone tools to render their Markdown pages into HTML and MS Word formats. I will demonstrate how R Studio plus Bookdown can turn a collection of Markdown files into a book that can be hosted online or printed.
Participants will leave this workshop with a complete copy of the Science Writing Resource Guide that they can revise to match their local needs, experience writing and editing Markdown, and a personal GitHub account from which to share their work with others or launch a book project (say, a new lab manual) of their own. Participants’ new and edited pages will help us identify what additional topics should be added to our Resource Guide. Those who are interested can learn how they can contribute and publish new materials to our Guide.
Give yourself enough time to install the software. GitHub Desktop takes 10-15 minutes to install. Registering for a new GitHub account takes 5-10 minutes. If you do not have it already, R Studio Desktop takes 10-15 minutes to install.
If an installation does not work, do not worry. We will troubleshoot installations at the beginning of the workshop, and we have workarounds if needed.
GitHub is a free/low cost, secure collaboration and code sharing site that is popular with data scientists and program developers. GitHub also is becoming a popular hub for hosting blogs, static websites, and e-books (for example, Using Markdown inside R.) GitHub Desktop greatly simplifies installation, creating an account, and handling repositories.
Go to GitHub and follow their instructions for installing GitHub Desktop on your computer: Downloading and Installing GitHub Desktop
If you want to take a look around the application, Getting Started With GitHub Desktop is a good resource for learning what this program can do.
GitHub Desktop should ask if you want to log into an existing account, or create a new one. If it does not do that automatically, go to the GitHub home page and follow the prompts to register. You do not need a private account for this workshop. If you start using GitHub regularly, a private account costs ~$50/year. GitHub definitely is a good investment; backups have saved me several times after I accidentally deleting important files.
If you have participated in one of ABLE’s prior workshops on R or R Studio, you may have these programs installed already. If not, download and install R (the engine) before R Studio Desktop (the user interface) on your computer. Usually both installations run smoothly without you having to do anything.
Here are illustrated instructions for installing R & RStudio.
For even more detailed instructions, consult Installing R and R Studio, Step by Step
GitHub stores files related to a project in a special folder called a repository (aka, “repo”). GitHub users can create separate repositories for different projects. Private repositories can only be seen by their owner and other GitHub users that the project owner specifies. Public repositories are available for anyone to view or copy, but users cannot add new files, or revise or remove existing files without the repository owner’s express permission.
You do not have to be subscribed to GitHub to copy a public repository or use the files in it; you can download the contents of any public repository as a ZIP archive. However using GitHub to manage repositories can help you keep projects organized, and share them more efficiently.
When you first install GitHub, you create a dedicated space inside your computer for storing repositories. After that you can make a copy of any repository you have rights to see and store that copy in your own GitHub account. The repository will be copied to your local space, and backed up online. Your copy contains all of the files that were in the project’s original repository.
There are three kinds of GitHub copies: clones, forks, and branches (which we will not use). A clone is a completely independent copy. When you clone someone else’s repository, GitHub will tell you if there have been changes made to the original source repository, but those changes are not added to your copy, and any changes you make to your copy do not affect the source. We usually clone repositories when we want to use the files independently from their original authors.
A fork is a repository copy that stays connected to its parent. All of the users are working collaboratively on the same set of files at the same time. Unlike a Google document though, changes made by collaborators have to be approved by the owner of the repository. Once changes are approved, they are merged into the repository and “pushed” to all collaborators’ copies of the repository. Forked repositories are useful when multiple authors work on one project. Every change is documented along with who made it. Individuals can work on separate files (and even different versions of the same file) without interfering with each other. Earlier versions of every file are available from the file archive.
In this exercise you will be cloning the ABLE 2022 Workshop repository. You can edit any page or add new pages without damaging the source files. If you make a mistake in a document and cannot fix it, just download a new copy. You’ll also be using the Commit and Push commands. Do not worry about what they mean right now; we will talk in detail about them in Exercise 3.
Use a web browser to log into your GitHub account.
Click on the URL (or type it in) to go directly to the ABLE workshop repository: https://github.com/adanieljohnson/ABLE_2022_Workshop. Alternatively, go to GitHub, look for the Search window at the top left, and enter adanieljohnson/ABLE_2022_Workshop. This is a shortcut to the project repository.
What you see will be something similar to the screenshot below. Click on “Code” to open the window with the link to clone this repository.
Main page of ABLE Workshop repository
Orange arrow marks the URL to clone the repository.
GitHub Desktop
Your copy of the ABLE 2022 Repository
Committing changes to your local copy of the files.
Pushing a copy of your changes to your main GitHub account
Now that your repo is saved, we can play. Open the folder named Sample Files. It contains the original .md file for the handouts for this workshop, and corresponding HTML and MS Word files, rendered using different methods. Open the .md file, then open one of the files with either the .html or .docx extension.
Using Handout for Exercise 1 as your “.md to .html/.docx dictionary,” try to translate the markup in the .md files. As you work, think about these questions:
If you make changes to your .md files, be sure to save them before going on to Exercise 2.
Markdown was created as a way for writers to annotate thir text quickly to show formatting without having to embed full HTML tags. The goal with Markdown is to separate the content (words of the text) of a document from the format (headers, paragraphs, bullets, etc.) from the. If we use one well-defined set of marking conventions (called the syntax), we can use converters to read a marked-up text and render it to many different formats. For example, the converter we will be using can read Markdown and export it in any of >30 other text formats.
Here is some text that has been formatted using Markdown:
There are two main kinds of text formatting:
Here is the same text that has been formatted so you can see the markup:
#### Level 4 Header - Formatting
There are two main kinds of text formatting:
* Inline formatting (_italics_, subscripts like H~2~SO~4~, etc.)
* Block- or paragraph-level formatting (headings, sub-headings, etc.)
The number of hash (#) marks indicates the level of the header. Lines of text are separated by an extra space. Words or blocks of text that have specific formatting are surrounded by a pair of symbols indicating the type of formatting to apply. Here is what the same text looks like rendered:
The rest of this handout explains the markup codes that you need most often. Keep a copy handy until you can remember the specific codes reliably. Better yet, copy the text of the original .md file and edit it to suit your own needs.
The table shows how to mark text, and what it will look like when rendered.
| Inline Formats | How to Mark Them | How They Appear |
|---|---|---|
| Italics | _italicized_ word | italicized word |
| *italicized* word | italicized word | |
| Bold | __bolded__ word | bolded word |
| **bolded** word | bolded word | |
| Bold Italics | ___marked___ word | marked word |
| ***marked*** word | marked word | |
| Superscripts | Super^script^ed letters | Superscripted letters |
| Subscripts | Sub~script~ letters | Subscripted letters |
| Horizontal rule | *** | Draws a line across page _____ |
| Inline code (not rendered) | `code block` | code block |
| Escape a special character | \*code block\* |
*code block* |
| Links to web pages | [text](link) |
RStudio |
| Links with URL | [link](link) |
https://www.rstudio.com |
| Embed local images | . |
|
| Embed images from web | . |
Header levels are indicated with 1-6 hash marks followed by a space.
| Block Formats | How to Mark Them |
|---|---|
| Level 1 Header | # Level 1 Header |
| Level 2 Header | ## Level 2 Header |
| Level 3 Header | ### Level 3 Header |
| Level 4 Header | #### Level 4 Header |
| Level 5 Header | ##### Level 5 Header |
| Level 6 Header | ###### Level 6 Header |
How they render:
Regular paragraphs need to be separated by a blank line, or they will run together. For example, a text written like this, without spacing lines:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Looks like this when rendered:
There are several kinds of text formatting to explore.Inline formatting text.Block- or paragraph-level formatting.Lists and quotes.
Text written WITH spacing lines like this:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Renders like this:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Blockquotes are written after the “>” symbol. A new “>” symbol is needed after each line break. This text:
> "I thoroughly disapprove of duels. If a man should challenge me,
I would take him kindly and forgivingly by the hand and lead him
to a quiet place and kill him."
>
> --- Mark Twain
Renders like this:
“I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.”
— Mark Twain
Blocks of text that should be displayed as written and not be rendered are enclosed between three backticks. Blocks typed like this:
``` Block of text or code that should NOT be rendered, like this __bold__ word. ```
are rendered like this:
Block of text or code that should NOT be rendered, like this __bold__ word.
Bulleted or unordered lists need to be separated from the preceding paragraph by a blank line. The items start with *, +, or -, and you can nest one list within another list by indenting the sub-list by four spaces. For consistency, it is best to make it a habit of using one character for main bullets, and the other two for sub-bullets.
A coded list looks like:
* First item
* Second item
+ First sub-item
- First sub-sub-item
- Second sub-sub-item
+ Second sub-item
* Third item
The output renders as:
Ordered list items start with numbers, but the rule for nesting are the same as for unordered lists.
1. First item
2. Second item
1. First sub-item
1. First sub-sub-item
2. Second sub-sub-item
2. Second sub-item
3. Third item
The output renders as:
The two formats can be mixed together:
1. First item
+ Sub-item
+ Sub-item
2. Second item
3. Third item
Renders as:
Numbered lists can be a bit fussy in Markdown. Sometimes they default to starting with #1. There is no simple and consistent way to force a list to start with a particular number. I usually fix this by editing the HTML or Word document directly, or just pre-number lists myself.
Inline equations are written using standard LaTeX syntax, and enclosed by pairs of $ signs. This code:
$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$
Renders an inline version of the equation as:
\(f(k) = {n \choose k} p^{k} (1-p)^{n-k}\)
Equations in display style are written enclosed in a pair of double dollar signs. This code:
$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$
Renders as:
\[f(k) = {n \choose k} p^{k} (1-p)^{n-k}\]
Other Tips on Equations:
There are some formats that Markdown does not handle well. For example, subscript and superscript marks may not work on the first character or number in a word (like 3H) or on a whole word. Some other useful items are not in the GHFM syntax at all. You can fill in these gaps with a few basic HTML codes.
| If you need to… | Insert this HTML snippet | For this result |
|---|---|---|
| Force a superscript for a whole word or first character | <sup>super</sup>script |
superscript |
| Force a subscript for a whole word or first character | <sub>sub</sub>script |
subscript |
| Strike through text | <strike>This</strike> word |
|
| Add an extra space between items | |
|
| Add an extra line between items | <br> |
|
| Add a horizontal rule between lines | <hr/> |
_____ |
| Add Greek letters | α, η |
α, η |
This page is a good source for other HTML shortcuts. You csan find more information about special symbols here.
These web resources can help you expand your Markdown writing skills. More are listed in the Notes for Instructors.
Publishers and full-time content writers know it is easier to manage a large number of complex documents when you have a consistent authoring and publishing workflow. Markdown is intended for the start of the authoring workflow, and assumes that text needs to be used and reused across multiple formats. MS Word is desktop publishing software, meaning it is designed to produce polished print documents at the end of the authoring and publication workflow. That is why Word files include a lot of hidden styling information that hampers reusability.
For example, if you have ever converted a long Word document into a web page, or combined several documents into one, you probably have seen unpredictable changes in format. This happens because of the embedded, hidden styling information. Markdown does not hide the formatting information, making it much easier to combine and convert documents.
Markdown has other advantages beyond “write once, reuse many ways.”
Markdown files are VERY small compared to Word .docx files. For example the Markdown file containing the full set of handouts for this workshop is 54KB; the corresponding Word file is 3.8 MB (70x larger.)
Markdown files do not contain embedded images. They use an address to “call in” images when the document is rendered. This means one master set of images can be stored in a single location, and called into any Markdown document. If an image is updated, every document or web site that uses that image will use the new version the next time the file is generated.
When a Markdown file is converted to a document format, all of the headers, bold words, etc., get tagged with appropriate styling codes for that document type. This greatly reduces time spent reformatting converted documents.
Markdown is truly platform-agnostic. The same file can be edited on a Mac, a PC, and a Linux machine, and never have any compatibility problems.
Many tools for using Markdown are available for free.
Unlike HTML, Markdown does not require any special code or starting text at the beginning of a new document. The only requirement is that the saved text file should have .md as the extension.
There are many ways to write Markdown files. You can:
Which will work best for you depends on your personal preferences, and how you plan to use the files. You may end up using some of all three methods. The goal of this exercise is to introduce you to each method, so you can find a workflow that feels comfortable to you.
Personal Tidbit: my own workflow changes with what I am doing. Right now, most of my writing ends up on our campus LMS so it needs to be plain HTML. Occasionally I write handouts that need to be in MS Word (.docx) format. I prefer to write drafts in a commercial plain text editor that shows Markdown codes in color. I work across multiple computers, so even the early draft files go into a GitHub repository so I can access them anywhere.
When it is time to generate output, the text editor I use converts Markdown directly to plain HTML that I can copy/paste straight into our LMS. I use R Studio to generate MS Word documents and build online books. I rarely make PDFs anymore because they are hard for screen readers to translate.
In this exercise you will try writing and editing Markdown texts using R Studio as a text editor, then using a standalone text editor. Your goal is to experience for yourself how Markdown behaves in different editing environments. One probably will feel more comfortable than the other; that is the way you should start out building your editing workflow.
Open R Studio, and choose__File > Open__ and navigate to the ABLE 2022 Workshop repository. Open to the file containing the Table of Contents page for the Writing Resource Guide.
Find 1-2 EXISTING pages you think you might want to edit or contribute to. Also find 1-2 topic that you do not see in the current pages that you think should be in the Guide.
Now open the folder named Writing Resource Guide. It contains the Markdown files (with the “.md” extension) for the full Writing Resource Guide. Locate one of the pre-existing .md files you wanted to edit, and open it.
Next you will start a new file. Choose File > New File > Markdown file.
Start a new .md file
Enter some starting text. One or two words is enough.
Save the file in your ABLE 2022 Workshop repository. Give your file a name that reflects the topic you did not see. Include the .md extension. TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)
Now you have a starting file that you can edit any way you wish.
When you are finished editing your two pages, save them both in the ABLE 2022 Workshop respository folder.
Close R Studio for now.
Navigate to your ABLE 2022 Workshop repository folder. Usually it is located in your Documents folder.
Click on one of the .md files in the Writing Resource Guide folder to select it. This time you want to open the file in a plain text editor.
After you have edited an existing .md file, try creating a new one from scratch. Once again, create a new file for a topic you think is missing from the Table of Contents of the Resource Guide.
When you have finished, save both of your edited .md files.
The workflow for creating and editing .md files in a browser is a bit different. These instructions only work while you are online and logged into GitHub.
In a browser, log into GitHub (not Desktop). Go to the repository containing your cloned copy of the Resource Guide. At the top of the list, click on Add file. Choose Create new file.
Give your file a name that reflects the topic you did not see. Include the .md extenstion.
Enter some starting text. One or two words is enough.
At the bottom of the page is the Commit dialog. GitHub requires you to describe what you did when you save a file. That information goes in the first box, and is required. It might seem like extra trouble at first, but when you are making changes in critical files, these commit comments can help you track what changes you made and when. If there are multiple authors working on a file, each author’s changes should say specifically what they worked on.
Commit the file directly to the master (branches and pull requests are not important until you are working on more complex projects.) TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)
Now you have a starting file that you can edit any way you wish. If you want to see how changes to the Markdown code affect it, simply click the Preview tab at the top of the window.
Next, go back to the Table of Contents and find a page you think you might want to edit. Locate the corresponding pre-existing .md file, and open it.
You have edited and saved your .md files locally. Now the local repository on your computer is ahead of the version in your GitHub account! In this exercise we’ll synchronize the two repositories by pulling and pushing files between them.
Do I HAVE to use GitHub? Nope, it is entirely up to you. You can copy files from any GitHub public repository; only the private repositories are restricted to account holders. If you never share files with other people, only work with local copies, and have a good back-up service already, then you may not need it.
GitHub has many benefits though. You can share files with others, get their suggestions, then decide whether or not to incorporate them. If you work across multiple computers (home and work for example), GitHub helps ensure you always are working on the most recently updated files. You also can set up a personal web site for each repository you have. If you are interested in using R or data science tools in your lab courses, then you definitely want to become comfortable using GitHub.
GitHub has two functions that help you keep repositories in sync: pull (sometimes called fetch) and push. These commands can be confusing, but they are at the heart of what makes GitHub so powerful.
When you pull (or, fetch) a copy of a repository, GitHub compares the versions of the files in the repository on its servers and your local computer. If the server version does not match the local version exactly, GitHub will try to download the newer version and update the older version on your local computer. If there are newer versions in BOTH locations, GitHub will ask you to pick one to be the new “correct” version.
Say you have been editing several .md files using the text editor on your computer. When you commit the files, you are telling GitHub “these are the newest versions, and what everyone should be using from now on.” GitHub dutifully stamps them with a time and location code, and stores them locally. You need to push the files to tell the main GitHub server to update its copies.
When you push files, the server compare its copy of each file to the data stamp on the one you pushed. If there are changes in the server copy that are not in yours, GitHub will stop and tell you that you need to pull the changes already logged by the server and merge them with your local changes first. Then you can push the newest version of each file back to the server. This is a quirk of GitHub; usually pulling from the server resolves any conflicts.
Why does GitHub use so many different commands? Why not just save a file instantly and everywhere, like Google does? If you have ever had someone change a Google document you just finished editing back to what you deleted, you know why. GitHub’s strategy is designed for code writers and editors. There has to be one “correct”” version, and one person with the authority to make the decision what files are correct. Committing a file only saves it to the local copy of the repository you happen to be working in. Pushing a file changes it on the main server, and on all of the forked copies.
Open GitHub Desktop. If you are not logged in to your account, do so now.
In the upper left of the work window, click on Current Repository. Pick the ABLE 2022 Workshop. You now should see a list of files that changed. The files you created or edited should be listed.
Setting the repository to synchronize.
In the upper part of the work window, click on Fetch Origin. This issues a Pull command; it pulls information about the server version of the repository and compares the two versions.
You should see a list of files that have changed since they were last saved to your account. Give your update a SHORT name. Then click on Commit to save the changes locally.
Committing changes to your local copy of the files.
Pushing a copy of your changes to your main GitHub account
How often should you commit and push? It is up to you, but generally you should commit every 30-60 minutes, or right after you complete a set of major edits. You might only push changes to GitHub once or twice a day, though more often does not hurt anything. It is a good habit to push to GitHub when you finish working for the day.
Why commit so often? GitHub creates a detailed record of every Commit and Push command in your account that includes which files were changed and how. If you are editing a large file or several files and accidentally delete some important text, you can use the repository history to reconstruct the missing pieces. The more often you Commit, the finer grained the record of changes.
In Exercises 1-3 you learned how to create, edit, and manage Markdown files. Now we are going to create documents with those files.
Markdown can be converted to other document formats using Pandoc, a “universal document converter.” It can read many different document file types, then convert one format to another. Some file types get fussy when converted, but Markdown and Pandoc play very nicely together.
There are several ways to access Pandoc; you do not need to work with it directly. In this exercise you will be using a standalone web-based converter to create clean HTML, and using R Studio to create MS Word documents. I will demonstrate two other routes: using the command line to build single files, and using R Studio’s bookdown package to compile single files into an e-book.
Many plain text editors (though oddly, not R Studio) can convert Markdown to very compact plain HTML. If your text editor does not have this feature, this web-based Pandoc converter works well.
Go to the MD to HTML Converter at https://ashkanph.github.io/md-to-html/.
In the upper right corner, use Browse to find your local GitHub folder, and choose one of your recently edited .md files.
The .md file will be converted to .html and displayed.
Use the Save as HTML button to write a copy of the file in .html back to your local GitHub folder.
If you open the version of the file with the .html extension in your plain text editor, you will see it has been rewritten using HTML markup. You can copy and paste the HTML code into most LMS pages. Alternatively, you can share the file itself with others; they can open it in any web browser.
Why not use R Studio for HTML? When R Studio generates standalone HTML files, it embeds the raw code for every image plus a LOT of extra styling code. For example, the HTML file containing the handouts for this workshop that was generated using the Ashkanph converter is 63 Kb. The same HTML file generated using R Studio is 6 Mb. This problem goes away when R Studio creates books; the HTML files are very compact, because they reference separate styling and image files rather than embedding them.
There are many free MD to HTML converters available. Two very good ones are Markdown It and Markdown to HTML; both have very user-friendly interfaces, but require copy/pasting the text rather than choosing a file.
Dillinger is a web-based editor that shows the Markdown code in a window next to either the HTML code or the styled text. Rendered Markdown can be exported as HTML, but like R Studio, Dillinger includes some extra styling information.
If you prefer to use a standalone Markdown editor, HarooPad produces very clean HTML. HarooPad handles equations particularly well.
R Studio is very good for converting .md files to well-formatted Word documents.
Open R Studio, and go to the workshop files. Open one of the files you edited or created.
At the top of the screen, open the pulldown menu next to Preview and choose Word document.
Converting Markdown to Word format
R Studio will call Pandoc, generate a pre-formatted MS Word .docx file, then save it to the same directory where the .md file is located.
Click on the .docx file to open it in MS Word.
MS Word files are formatted using a standard template. To format documents a different way, create a template file with the header and text styles that you want. When newly generated documents are copy/pasted into the template file, the text will change to the styles you set.
It is very easy to install and run Pandoc from your computer’s command line, and it generates both .docx and .html files. If you would like to try it yourself:
Go to the Pandoc installation page for instructions to download and install to your computer.
Use the following Terminal commands to convert from .md to .html or .docx format. The commands are the same, except for the extension on the output file.
pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.html
pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.docx
Pandoc is fussier about rendering PDFs. First, it does not tolerate markup errors, and may refuse to convert a file. Second, you must install a pdf-engine then call it in the command. Look at the example below:
pandoc -s --pdf-engine=xelatex /filepath/Input_Filename.md -o /filepath/Output_Filename.pdf
The pdf-engine defines what the format will look like. This particular PDF engine’s default layout and fonts look outdated and can be hard to read. Changing them requires some deeper coding work, which is why I do not recommend using Pandoc for creating occasional PDFs. It is quicker to render a file in MS Word then save it as a PDF.
R has powerful libraries for creating online materials. The bookdown package (which uses knitr plus Pandoc) combines individual .md files into full length technical books. The Home page for the R Bookdown package has examples of books that were created this way.
There is not enough time for you to set up your own GitHub-hosted book from start to finish. Instead, we’ll take a short tour through the back end of the SWP Writing Resource Guide and see how R Studio turned a collection of separate .md files into an integrated book.
We also will talk about what is missing from the Resource Guide that you added, and your suggestions for improving it.
Today’s exercises introduced you to most of the tools you need to start using Markdown.
If you want to use our Writing Resource Guide in your own courses, you now have the original documents and all the tools you need to edit it to suit your program needs. If you are interested in writing new material or helping us expand the Guide, let us know.
If you want to try building your own online book, go to our Bookdown Demo repository, which is an unmodified fork of a demo by bookdown’s creator, Yihui Yue. Clone this to a new repository, and you have a complete operating skeleton for a book. Authoring Books and Technical Documents With R Markdown describes how to customize it as you desire.
Two other books that can help you continue developing your skills are:
Links to packages and resources described in the workshop handouts are provided again here for convenience, along with additional resources.
Participants will need to have a laptop that can connect to the internet, and access to a web connection. Tablets are not going to work; GitHub Desktop does not work as an app. It may be helpful to have 2-3 loaner laptops in the event someone only has a tablet.
The workshop can be conducted in a computer lab, but it would be better if participants used their own computers, so they leave with the full set-up needed to continue using the materials at home.
I plan to use this section to summarize feedback and answer questions received during the workshops. Topics I expect will be covered here includes:
The working template version of the Resource Guide that participants will clone to their own accounts for editing, a copy of the .md file used to create the handouts, and all other files for the workshop will be available from the workshop’s public GitHub repository.
Participants will learn to use Markdown, GitHub and GitHub Desktop, and Pandoc text converter in the context of a collaborative writing project.
Markdown is a lightweight but very versatile text markup language that lets authors write well-structured texts once then reuse them multiple ways. It is extremely easy to learn (<20 minutes for 90% of what you will use routinely), and text with Markdown tags remains easy to read. I estimate that >80% of the new materials I write now start out in Markdown.
There are several “flavors” of the original Markdown language standard. I chose the GitHub “flavor” of Markdown (GHFM) for the workshop because:
GitHub is best known as a place where data scientists share code, but it works equally well as a no/low cost, secure project space that operates seamlessly between institutions. GitHub also is becoming a destination for hosting blogs, static websites, and open-access book projects.
Many ABLE members already know R and R Studio, but likely think of them more as a platform for statistics and numerical data analysis. When combined with GitHub and Markdown, R Studio becomes a powerful text editor, integrated development environment, and project management space.
Prior to the workshop, participants will register for a free GitHub account and connect GitHub Desktop to their GitHub account. They also will install R and R Studio. These installations are straightforward, but in the event participants have trouble, they can work with a partner while we complete their setup in the first few minutes of the workshop.
During the first 60 minutes of the workshop, participants will copy the text files for the Writing Resource Guide from a sandboxed repository I have set up for this workshop to their personal GitHub accounts. Using both R Studio and a plain text editor, they will edit an existing page, then create a new page for a topic they think is needed. By break time, participants will have completed their writing and saved their modified files back to their personal accounts.
After the break (assuming 30 minutes), participants will spend the next 60 minutes converting their edited Markdown pages into well-structured documents. They will learn to generate files in two formats:
There is not enough time to set up a complete GitHub-hosted book. Instead, I will use the remaining ~30 minutes to demonstrate how R Studio’s knitr and bookdown R libraries can compile individually edited pages into a GitHub-hosted e-book.
Participants will leave with a complete copy to our Science Writing Resource Guide which they can use in their courses. Their computer will be set up and ready to use GitHub Desktop and R Studio to continue editing their copy of the Guide, and they will have a GitHub account that they can use to build books or share pages with others. They also will have the resources needed to convert their work into MS Word or HTML documents.